/*
** $Id: lmem.h,v 1.43.1.1 2017/04/19 17:20:42 roberto Exp $
** Interface to Memory Manager
** See Copyright Notice in lua.h
*/

#ifndef lmem_h
#define lmem_h


#include <stddef.h>

#include "llimits.h"
#include "lua.h"


/**
 * 重新分配向量 'b' 的大小，从 'on' 个元素扩展到 'n' 个元素，每个元素的大小为 'e'。
 * 如果 'n' * 'e' 的乘积导致算术溢出，则会调用 'luaM_toobig' 抛出错误。
 * 由于 'e' 始终为常量，因此避免了运行时计算 MAX_SIZET/(e)。
 *
 * 宏的实现较为复杂以避免编译器警告：
 * - 使用 'sizeof' 比较来避免在不会发生溢出时进行运行时比较。
 * - 编译器通常会优化实际的测试，但可能会生成关于“由于数据类型范围限制，比较始终为假”的警告；
 *   通过 '+1' 的技巧可以避免此警告，同时保留优化。
 */
/*
** This macro reallocs a vector 'b' from 'on' to 'n' elements, where
** each element has size 'e'. In case of arithmetic overflow of the
** product 'n'*'e', it raises an error (calling 'luaM_toobig'). Because
** 'e' is always constant, it avoids the runtime division MAX_SIZET/(e).
**
** (The macro is somewhat complex to avoid warnings:  The 'sizeof'
** comparison avoids a runtime comparison when overflow cannot occur.
** The compiler should be able to optimize the real test by itself, but
** when it does it, it may give a warning about "comparison is always
** false due to limited range of data type"; the +1 tricks the compiler,
** avoiding this warning but also this optimization.)
*/
#define luaM_reallocv(L, b, on, n, e) \
  (((sizeof(n) >= sizeof(size_t) && cast(size_t, (n)) + 1 > MAX_SIZET/(e)) \
      ? luaM_toobig(L) : cast_void(0)) , \
   luaM_realloc_(L, (b), (on)*(e), (n)*(e)))

/*
** Arrays of chars do not need any test
*/
#define luaM_reallocvchar(L, b, on, n)  \
    cast(char *, luaM_realloc_(L, (b), (on)*sizeof(char), (n)*sizeof(char)))

#define luaM_freemem(L, b, s)  luaM_realloc_(L, (b), (s), 0)
#define luaM_free(L, b)    luaM_realloc_(L, (b), sizeof(*(b)), 0)
#define luaM_freearray(L, b, n)   luaM_realloc_(L, (b), (n)*sizeof(*(b)), 0)

#define luaM_malloc(L, s)  luaM_realloc_(L, NULL, 0, (s))
#define luaM_new(L, t)    cast(t *, luaM_malloc(L, sizeof(t)))
#define luaM_newvector(L, n, t) \
    cast(t *, luaM_reallocv(L, NULL, 0, n, sizeof(t)))

#define luaM_newobject(L, tag, s)  luaM_realloc_(L, NULL, tag, (s))

/**
 * 这段代码是一个宏定义，用于在 Lua 中动态增长一个向量（也就是数组）。
 * 宏 luaM_growvector 用于当当前向量的容量不足以容纳更多元素时，自动扩展向量的大小。下面是对宏中每个部分的解释：
 * 1. L：是一个 lua_State * 类型的参数，指向当前的 Lua 状态。
 * 2. v：是指向当前向量的指针，其类型是 t *，t 是向量中存储元素的类型。
 * 3. nelems：是一个整数，表示当前向量中已有的元素数量。
 * 4. size：是一个整数，表示当前向量分配的容量（即可以存储的元素数量）。
 * 5. t：是向量中存储元素的类型。
 * 6. limit：是一个整数，表示向量容量的最大限制。
 * 7. e：是一个表达式，用于在需要增长向量时，创建新的元素的默认值。
 * 宏的工作流程如下：
 * 首先，检查当前向量中的元素数量 nelems 加一（因为我们要添加一个新元素）是否大于当前向量的容量 size。如果是，说明向量需要增长。
 * 如果需要增长，执行 luaM_growaux_ 函数。这个函数负责实际的内存重新分配和向量增长工作。
 * 它接收 Lua 状态 L、当前向量 v、指向容量 size 的指针、元素类型 t 的大小、最大限制 limit 和默认值表达式 e。
 * cast(t *, luaM_growaux_(L, v, &(size), sizeof(t), limit, e))：这将 luaM_growaux_ 函数的返回值转换为 t * 类型，
 * 即向量的元素类型指针类型，并将其赋值给 v。这更新了向量的指针，使其指向新的、更大容量的内存区域。
 * luaM_growaux_ 函数可能会根据需要创建一个新的更大的内存块，将旧向量中的元素复制到新内存块中，并使用 e 表达式初始化新增加的空间。
 * 这个宏是 Lua 中动态数组管理的一部分，通常用于实现 Lua 表（tables）、栈和其他需要动态增长的数据结构。
 * 通过这种方式，Lua 可以有效地管理内存，避免在添加每个元素时都进行显式的内存分配检查。
 */
/**
 * @brief 动态扩展向量（vector）的内存空间。
 *
 * 当向量的元素数量（nelems）超过当前分配的大小（size）时，调用此宏会自动扩展内存空间。
 * 扩展后的内存空间大小会根据给定的限制（limit）和错误处理方式（e）进行调整。
 *
 * @param L Lua状态机指针。
 * @param v 指向向量的指针。
 * @param nelems 当前向量的元素数量。
 * @param size 当前向量的内存大小（以元素数量计）。
 * @param t 向量元素的类型。
 * @param limit 向量扩展的最大限制。
 * @param e 内存分配失败时的错误处理方式。
 */
#define luaM_growvector(L, v, nelems, size, t, limit, e) \
          if ((nelems)+1 > (size)) \
            ((v)=cast(t *, luaM_growaux_(L,v,&(size),sizeof(t),limit,e)))

/**
 * @brief 重新分配一个动态数组的内存空间。
 *
 * 该宏用于重新分配一个动态数组的内存空间，支持调整数组的大小。
 * 它会调用 `luaM_reallocv` 函数来完成实际的内存分配操作，并更新指针 `v` 指向新的内存地址。
 *
 * @param L Lua 状态机指针。
 * @param v 指向动态数组的指针，将被更新为新分配的内存地址。
 * @param oldn 当前数组的大小（元素数量）。
 * @param n 新数组的大小（元素数量）。
 * @param t 数组元素的类型。
 *
 * @note 这是一个底层宏，通常用于 Lua 内部实现，不建议在用户代码中直接使用。
 */
#define luaM_reallocvector(L, v, oldn, n, t) \
   ((v)=cast(t *, luaM_reallocv(L, v, oldn, n, sizeof(t))))

LUAI_FUNC l_noret luaM_toobig(lua_State *L);

/* not to be called directly */
LUAI_FUNC void *luaM_realloc_(lua_State *L, void *block, size_t oldsize,
                              size_t size);

LUAI_FUNC void *luaM_growaux_(lua_State *L, void *block, int *size,
                              size_t size_elem, int limit,
                              const char *what);

#endif

